MacFormat 1995 April/macformat-023.iso/Shareware City/Applications/chipmunkbasic3.10/basic.man

Text File | 1994-12-20 | 19.2 KB | 759 lines | [TEXT/ttxt]

    BASIC(1)        chipmunk-basic v3.1             BASIC(1)


    Chipmunk BASIC - 'BASIC' language interpreter


    SYNOPSIS    ( UNIX )

    basic [ filename ]

    DESCRIPTION

    Chipmunk basic is an interpreter for the BASIC language. If a
    filename parameter is given, then the named program file is
    loaded and run as a Basic program.

    Basic commands and statements can be entered and interpreted in
    immediate mode or executed as program statements when the Basic
    program is run.  A built-in line number based editor allows
    program input from the console keyboard.  See below for the
    commands the interpreter recognizes.

    FLAGS

    none

    COMMANDS

    Standard mumbleSoft Basic Commands:

    load STRINGEXPR

        Load a program into memory from the named file. The
        program previously in memory is erased.  All
        variables are cleared.  All lines in the file must
        begin with a line number.  Line numbers do not
        need to be in increasing order.


    save STRINGEXPR

        Save the current program to a named file.

    new

        Erase the program in memory.  All files are closed and
        all variables are cleared.

    clear

        All  variables are cleared.  All arrays and string
        variables are deallocated.

    run { LINENUM }
    run { STRINGEXPR { , LINENUM } }

        Begin execution of the program at the first line, or at
        the specified line.  All variables are cleared.  If a
        STRINGEXPR is given then the BASIC program with that name
        file is loaded into memory first.  Program lines are
        executed in line number order.

    cont

        CONTinue execution of the program on the next statement
        after the statement on which the program stopped execution
        due to a STOP command or an error.  See BUGS section.

    goto LINENUM

        This statement will transfer control to the line number
        specified.  If the program is not running, then this
        command will begin execution at the specified line
        without clearing the variables.  An "Undefined line"
        error will occur if LINENUM doesn't exist in the program.

    list
        List the whole program.

    list 1-3
        List lines 1 to 2

    list -2
        List lines up to 1

    list 1
        List line 1

    list 2-
        List lines from 2 on

    merge STRINGEXPR

        Load a program into memory.  The previous program
        remains in memory; if a line exists in both programs,
        the newly loaded line is kept.

    renum STRINGEXPR VAL { , VAL { , VAL { , VAL} } }

        Renumber program lines.  By default, the new sequence
        is 10,20,30,... The first argument is a new initial
        line number; the second argument is the increment
        between line numbers. The third and fourth arguments,
        if present, specify a limiting range of old line numbers
        to renumber.  RENUM can be used to move non-overlapping
        blocks of code.

    edit LINENUM

        Edit a given line. If the exit from the edit is via a
        cntrl-c then do not change the line.
            i    insert till <return>
            x    delete one char
            A    append to end of line

    delete LINENUM - LINENUM

        Delete a specified range of lines. If not found then no
        lines will be deleted.  If used inside a program, DEL
        will terminate execution only if it deletes the line on
        which it appears.

    exit
    bye
    quit

        Terminates the basic interpreter, ending program
        execution and closing all files.


    STATEMENTS

    { let } VAR = EXPR

        Assign a value to a variable.  Variable names can be up
        to 31 significant characters, consisting of letters,
        digits, underscores, and an ending dollar sign.
        Variable names are case-insensitive.  Variables can
        hold real numbers (IEEE double) or strings of up
        to 254 characters.  If the variable name ends with a
        "$" it holds strings, otherwise it holds numbers.  If a
        statement starts with a variable name then an implied
        LET is assumed.

    print or '?' VAL | STRINGVAL { { , | ; } VAL ... } { ; }
    print #FNUM, VAL ...

        This command will print its parameters. If a
        semi-colon is used between parameters then no spaces
        are inserted between those parameters.  The print
        output is terminated with a carriage return unless the
        parameter list ends with a semi-colon.  If a file
        descriptor is given then output is redirected to the
        given file.

        If a
            tab(VAL)
        is found in a print statement, then print output will
        skip to the horizontal position specified by VAL.

    input { # FNUM , } { STRINGVAR | VAR { , VAR } }

    input "prompt"; { STRINGVAR | VAR  { , VAR } }

        Input from a terminal or from a file. If the input is
        from the terminal then a prompt message can also be
        added.

        All input to string variables is "line input"; a whole
        input line will be read into one string variable.  This
        usage is different from other versions Basic.

    get STRINGVAR

        Gets one character from the console keyboard.  Blocking.

    cls
        Clear the terminals screen.  Leaves the cursor in the
        upper left corner.  For Applesoft BASIC fans, the "home"
        command will also do this.

    end

        Terminates program execution and returns to the command
        prompt.  Not required.

    stop

        Stops the execution of the program and returns to
        the command prompt.  Prints a "Break..." message.

    if EXPR then STATEMENT { : STATEMENT } { : else STATEMENT }
    if EXPR then LINENUM
    if EXPR

        The IF statement.  If the condition is true then the
        STATEMENTS after the THEN are executed and the
        statements after the ELSE are skipped.  If the
        condition is false then the statements after the "else"
        are executed instead.  If the item after "then" is a
        line number then a goto is executed.

        If the condition is true and there is no THEN on the
        same line, statements are executed until a line
        with an ENDIF is found.  (block IF() ... ENDIF)

    for VAR = EXPR to EXPR { step EXPR }

        Beginning of a "for next" loop.  It takes a starting
        value, a limit and an optional step argument.  If the
        step value is negative, the variable counts down.  The
        body of the loop is not executed if the end condition
        is true initially.

        Example:
            for i=1 to 10 : print i, : next i
            rem prints the numbers from 1 through 10

    next { VAR }

        End of a "for next" loop.  If the termination
        conditions are met then execution falls through to the
        following statement, otherwise execution returns to the
        statement following the corresponding "for" statement.
        The "next" does not need a variable name parameter.  If
        this is the case the innermost "for" loop is used.

    while { EXPR }

        Start of a WHILE loop. The loop is repeated until EXPR
        is false. If EXPR is false at loop entry, then the loop
        is not executed at all. A WHILE loop must be
        terminated by a WEND statement.

    wend { EXPR }

        Terminating statement of a WHILE loop.  If EXPR is true
        then exit the loop.  Only one WEND is allowed for each
        WHILE.  A WHILE-WEND loop without a condition will loop
        forever.

    gosub LINENUM

        Transfer command to a line number. Save return address
        so that the program can resume execution at the
        statement after the "gosub" command.  The recursion
        depth is limited only by available memory.

    return

        Returns from the most recently activated subroutine
        call (must have been called by gosub).

    on EXPR   goto  LINENUM { , LINENUM ... }
    on EXPR   gosub LINENUM { , LINENUM ... }
    on error goto  LINENUM

        This command will execute either a goto or a gosub to
        the specified line number indexed by the value of EXPR.

        If the error form is used, only one linenumber is
        allowed.  LINENUM is the line to which control is
        transferred if an error occurs.  A GOTO or CONT statement
        can be used to resume execution.  An error inside a named
        SUB subroutine cannot be resumed from or CONTinued.

    sub NAME ( VAR { , VAR ... } }

        Subroutine entry.  May be called by a GOSUB statement
        or by NAME. A SUB subroutine must be exited by a
        RETURN statement.  There should be only one RETURN
        statement per SUB subroutine.  The variables in the
        VAR list become local variables. String and numeric
        arguments are passed by value; array arguments must
        be pre-dimensioned and are passed by reference.

        Example:
            110  x = foo (7, j) : rem Pass 7 and j by value.
            ...
            2000 sub foo (x,y,z) : rem z is a local variable
            2010   print x       : rem prints 7 the first time
            2090 return (y+1)    : rem also restores x,y,z

    dim VAR( d { , d { , d } } ) { , VAR( d { , d { , d } } ) }

        Dimension an array or list of arrays (string or numeric).
        A maximum of 4 dimensions can be used. The maximum
        dimension size is limited by available memory. Legal
        array subscripts are from 0 up and including the
        dimension specified; d+1 elements are allocated.  All
        arrays must be dimensioned before use and can be
        dimensioned only once in a program.

        Example:
            10 dim a(10)
            20 for i=0 to 10
            30   a(i) = i^2
            40 next i
            50 print a(5) : rem should print 25

    read VAR { , VAR }

        Read data from the DATA statements contained in the
        program. List items can be either string or numeric
        variables. Reading past the end the last DATA statement
        generates an error.

    data ITEM { , ITEM }

        DATA statements contain the data used in the READ
        statements. Items must be separated by commas.  The
        items may be either numeric or string expressions,
        corresponding to the type of variable being read.
        Reading the wrong kind of object produces a "Type
        mismatch" error.

    restore { LINENUM }

        The RESTORE statement causes the next READ to use the
        first DATA statement in the program.  If a LINENUM is
        given then the DATA statement on or after that
        particular line is used next.

    rem or "`"

        A remark or comment statement.  Ignored by the program
        during execution, however a REM statement can be the
        target of a GOTO or GOSUB.

    open STRINGEXPR for { input|output|append } as # FNUM

        Open a file. The { input|output|append } parameter
        specifies whether the file is to be read, written or
        appended.  If STRINGEXPR is "stdin" for input or
        "stdout" for output then the console will be used
        instead of a file.  A "file not found" error will
        occur if a non-existant file is specified in an OPEN
        for input statement.

    close # FNUM

        Close a file. Releases the file descriptor and flushes
        out all stored data.

    def fnNAME ( VAR { , VAR } ) = EXPR

        Define a user definable function.

        Example:
            10 def fnplus(x,y) = x+y
            20 print fnplus(3,5) : rem prints 8

    { let } mid$( STRINGVAR, EXPR1, EXPR2 ) = STRINGEXPR

        Insert STRINGEXPR into STRINGVAR starting at EXPR1
        for character length EXPR2.

    exec(STRINGEXPR)

        Executes STRINGEXPR as a statement or command.
        e.g. exec("print " + "x") will print the value of x.

    poke ADDR_EXPR, DATA_EXPR

        Poke a byte into a memory location. Unreasonable
        addresses can cause bus-errors.

    push VAR { , VAR ... }

        Pushes one or more expressions or variables onto an
        internal stack.  Expressions can be returned using the
        POP function; variables can be returned by using the
        POP statement.

    pop VAL

        POP statement (see also POP function). Pops VAL
        variables off the internal stack, restoring the value
        of those variables to their pushed values.

    NUMERIC FUNCTIONS

    sgn(VAL)

        Returns the sign of the parameter value.  Returns 1 if
        the value is greater than zero , zero if equal to zero.
        -1 if negative.

    abs(x)

        Returns the absolute value of x.

    int(x)

        Returns the integer value of x.  Truncates toward zero.

    sqr(x)

        Returns the square root of x.

    log(x)

        Returns the natural logarithm of x.

    exp(x)

        Returns e^x. e=2.7182818...

    sin(x)
    cos(x)
    atn(x)

        Trigonometric functions: sin, cosine and arctangent.

    pi

        Returns pi, 3.14159265358979323...

    rnd(x)

        Returns a random number between 1 and int(x)-1.  If x
        is negative then x seeds the random number generator.
        If x is 1, then returns a fraction between 0 and 1.

    len(STRINGEXPR)

        Returns the length of the string STRINGEXPR.

    val(STRINGEXPR)

        Value of the expression contained in STRINGEXPR.
        STRINGEXPR may be a string literal, variable, function,
        or expression.

        For example, VAL("1+sqr(4)") yields 3.

    asc(STRINGEXPR)

        Returns the ascii code for the first character of
        STRINGEXPR.  A null string returns zero.

    instr(a$, b$ { , VAL } )

        Returns the position of the substring b$ in the string a$
        or returns a zero if b$ is not a substring.
        VAL is an optional starting position in a$

    eof(FILENUM)

        Returns true if the file specified by FILENUM has reached
        the end of the file.

    pop

        POP function (see also POP statement). Pops one variable
        value off the stack and returns that value (string or
        numeric).

        (POP can be used as either a statement (with a
        parameter) or a function (no parameter). Note that the
        POP function, unlike the POP statement, does not
        restore the value of the variable pushed, but only
        returns the pushed value.  This use of the POP
        statement is different from the Applesoft usage.)

    peek( ADDR { , VAL } )

        Returns the value of the byte in memory at address ADDR.
        If VAL is 2 or 4, returns the value of the 16-bit or
        32-bit word respectively (if correctly aligned).
        If VAL is 8, returns the value of the numeric variable
        located at ADDR.  peek(varptr(x),8) equals x.

    varptr( VAR | STRINGVAR )

        Returns the memory address of a variable.

    erl

        Returns the line number of the last error.  Zero if the
        error was in immediate mode.  The variable errorstatus$
        gives the error type.

    timer

        Returns a numeric value of elapsed of seconds from the
        computers internal clock.


    STRING FUNCTIONS

    x$ + y$

        String concatenation.  Result must be 254 characters or less.

    chr$(VAL)

        Returns the ascii character corresponding to the value
        of VAL.

    str$( VAL { , EXPR } )

        Returns a string representation corresponding to VAL.
        If EXPR is present then the string is padded to that
        length.

    inkey$

        Return one character from the keyboard if input is
        available. Returns a zero length string { "" } if no
        keyboard input is available.  Non-blocking.  Can be used
        for keyboard polling.

    input$( EXPR { , FILENUM } )

        Returns EXPR characters from file FILENUM. If f is not present
        then get input from the console keyboard.

    mid$( a$, i { , j } )

        Returns a substring of a$ starting at the i'th
        positions and j characters in length. If the second
        parameter is not specified then the substring is taken
        from the start position to the end of a$.

    right$(a$, EXPR )

        Returns the right EXPR characters of a$.

    left$(a$, EXPR )

        Returns the left EXPR characters of a$.

    field$( STRINGVAL, VAL { , STRINGVAL } )

        Returns the n-th field of the first string.  If the
        optional string is present then use the first character
        of that string as the field separator.  The default
        separator is a space.  Similar to UNIX 'awk' fields.

        e.g.  field$("11 22 33 44", 3)  returns  "33"

    hex$( VAL { , EXPR } )
    bin$( VAL { , EXPR } )

        Returns the hexadecimal or binary string representation
        corresponding to VAL.  If EXPR is present then the
        string is padded with zeros to make it that length.

    lcase$( STRINGVAL )

        Returns STRINGVAL in all lower case characters.

    errorstatus$

        Returns the error message for the last error.


    OPERATORS

    The following mathematical operators  are available:

        ^    exponentiation
        *    multiplication
        /    division
        mod    remainder
        +    addition
        -    subtraction

    logical operators: (any non-zero value is true)

            not    logical not

    bitwise operators:

            and    bitwise and
            or    bitwise or
            xor    bitwise exclusive-or

    comparison operators:

            <=    less than or equal
            <>    not equal to
            >=    greater than or equal
            =    equal
            >    greater than
            <    less than

    x$=y$, x$<y$, x$>y$, x$<=y$, x$>=y$, x$<>y$

        String comparisons; result is 1 if true, 0 if false.

    Operator precedence (highest to lowest):

        ( )
        not -{unary_minus} functions
        ^
        * / mod
        + -
        = < > <= >= <>
        and
        or xor


    UNIX commands and functions:

    sys( STRINGVAL )

        UNIX system call.  The string parameter is given to
        the shell as a command.

    argv$
        Returns the UNIX shell command line arguments.


    Macintosh commands:

    gotoxy VAL, VAL

        Set the horizontal and vertical location of the
        text output cursor.  (0,0) is the upper left corner.

    moveto VAL, VAL

        Sets the (x,y) location of the graphics pen.

    lineto VAL, VAL

        Draws a line from the current pen location to location
        (x,y) in the graphics window.

    window x, y, char_cols, char_lines

        Change the text console window position and size.

    graphics window x, y, char_cols, char_lines

        Change the graphics window position and size.

    morse STRINGVAL { , VAL, VAL, VAL, VAL }

        Plays morse code through the speaker.
        The parameters are { dot-speed-wpm, volume{0..100},
        word-speed-wpm, frequency_cps }

    sound VAL, VAL, VAL

        The parameters are
        { frequency_cps, seconds_duration, volume{0..100} }

    say STRINGVAL

        Speaks STRINGVAL if the Speech Manager Extension is
        resident.  Try "say a$,200,46,1" for faster speech.

    open "SFGetFile" for input  as #FNUM
    open "SFPutFile" for output as #FNUM

        Puts up a standard file dialog for the file name.

    call EXPR

        Calls the 68K code at address EXPR.

    Lots of other undocumented quickdraw and sprite commands.


    Macintosh functions:

    fre
        Returns the amount of memory left for program use.

    date$
        Returns a string corresponding to the current date.

    time$
        Returns a string corresponding to the current time.

    pos(VAL)

        Returns the horizontal position of the text cursor.
        If VAL is negative returns the vertical position.

    errorstatus$ also returns the full path name of the program and
        files opened by SFGetFile, under System 7 only, and only
        if the name fits in a string variable.


    Macintosh menu items:

    Open or <cmd>O     will put up a dialog to allow selection
            of a program file to load.  Basic Program file
            names must end with a ".bas" suffix.

    Copy        will allow copying picts from the graphics
            window.

    <cmd>.         command-period will stop program execution.

    Print        Only the graphics window can be printed.


    CONVENTIONS

    EXPR        any expression that evaluates to a numeric value.
    STRINGEXPR    a string expression.
    VAR        a numeric variable.
    STRINGVAR    a string variable.

    All program lines must begin with a line number.  A line number
    entered by itself will delete that program line. Using spaces
    (indentation) between the line number and program statements is
    legal.  Line numbers can be between 1 and 2147483647.

    Hexadecimal numbers can be entered by preceding them with
    a "0x" as in 0x02ae, or by "&h" as in &h0172.

    Multiple statements may be given on one line, separated by
    colons:

        10 INPUT X : PRINT X : STOP


    DIAGNOSTICS

    Some errors can be caught by the user program using the "on error
    goto" command. If no error trapping routine has been supplied
    then program execution is terminated and a message is printed
    with the corresponding line number.

    Graphics may require that the preferred memory requirements be
    increased.


    AUTHORS

    David Gillespie wrote basic.p 1.0 and the p2c lib.
    Ron Nicholson ([e-mail]) added file i/o and
    did the Macintosh and PowerMac port.  (1990-94Nov)


    BUGS

    Many.

    Can't CONTinue from an error inside a named SUB subroutine.

    Macintosh screen editing will only recognise the last line modified
    before a RETURN or ENTER key.

    There are several undocumented graphics and sprite commands
    and keywords.


    Portions Copyright (C) 1989 Dave Gillespie
    Copyright (C) 1994 Ronald H. Nicholson, Jr., All rights reserved.
    "Applesoft" is a trademark of Apple Computer, Inc.